home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 151-175 / scopedisk159 / parmenu / parm.doc < prev    next >
Text File  |  1995-03-19  |  11KB  |  304 lines
  1.  
  2. Documentation for ParM
  3.  
  4.  
  5. ParM stands for Parametrable Menu.
  6.  
  7. ParM allow you to build your own menus in order to run all the programs you
  8. can have on one ore more disks. This is very usefull for hard disk owners
  9. which have programs deeply enclosed in subdirectories. With ParM, you can
  10. run them without going through directories under either WorkBench or CLI.
  11.  
  12. With ParM, you can start programs in either WorkBench or CLI mode. The
  13. advantage of WorkBench mode is that the default directory of the program
  14. you run is the one in which the program file is. In the other hand, you
  15. can't leave ParM when workbench processes are running.
  16.  
  17.  
  18. Building:
  19.  
  20.     ParM was made using AztecC 5.0a, CygnusEd release 2, and ARexx 1.10. 
  21.     File headers are done in such a way compilation can be launched from
  22.     Ced. I use my own DevKit, completely rewriten since the original 1.2
  23.     version of the DevKit wasn't working at all.
  24.  
  25.     ParM needs arp.library version 39. Since linker libraries given with
  26.     arp 1.3 are for the 3.6 release of the Manx linker, I wrote prototypes
  27.     for all arp functions but Printf(), SPrintf() and FPrintf(). Theses
  28.     can't be prototyped because they have a variable number of arguments.
  29.     Then, I made a small library which only contain the glues for them,
  30.     called a.lib.  I make heavy use of Manx precompiled headers facility,
  31.     and I use only three headers of my own. They are called
  32.     dos_functions.h, dos_pragmas.h, and arpdos_pragmas.h. Of course, I have
  33.     removed dos functions prototypes from arpbase.h and functions.h to do
  34.     that.  I often use arp.library, and then, when I need dos functions, I
  35.     prefer arp ones, so I use arpdos_pragmas.h, otherwise, I use
  36.     dos_pragmas.h. In both cases, I include dos_functions.h, to have
  37.     automatic casts to long for short int parameters. (I allways use 16
  38.     bits ints) With this method, when I use dos fuctions, if I forget to
  39.     include dos_functions.h the compiler generates warnings telling no
  40.     prototypes have been defined for them. Then, I include dos_functions.h
  41.     and the pragmas needed. I have even a Ced macro to do that!
  42.  
  43.     Compiling with Lattice should be straight forward since ParM doesn't
  44.     use any of the specific Manx library functions. But I didn't try it
  45.     anyway.
  46.     
  47.  
  48. Installation:
  49.  
  50.     Put ParM with its icon wherever you want, and just put the default
  51.     config file "ParM.cfg" in S: if you use it. If you don't, you'll have
  52.     to specify the config file in the command line or in the tool types of
  53.     the icon, otherwise, you will have to cancel the requester and won't
  54.     have any menus.
  55.  
  56.  
  57. Running:
  58.  
  59.     It is recommended to run ParM from CLI if you want your programs to
  60.     have a default path other than the current directory and C: which is
  61.     the case if you start it from WorkBench.  ParM can be run in two ways. 
  62.     1) You can attach ParM to the CLI you are using.
  63.         In this case, if you don't specify any of the window options,
  64.                 the menus will be attached to the CLI window you start it 
  65.         from. You may then only "Run" it to prevent you from closing 
  66.         the CLI.
  67.     2) ParM can have its own window. This is allways the case when it is 
  68.         run from WorkBench, but you can also tell it to open it's own
  69.         window when run from CLI using "-w" option or any of the 
  70.         window options.  You should then "RunBack" it to be able to 
  71.         close the CLI later.  Don't use arp ARun with NOIO because 
  72.         some programs don't like it, and those will not run from ParM.
  73.  
  74.     ParM have some options which are available for most either from
  75.     WorkBench or from CLI. The only one which is only available from CLI
  76.     is "-w" since ParM allways open its own window when run from 
  77.     WorkBench.
  78.  
  79.     Option list:
  80.  
  81.     CLI       WB
  82.  
  83.     -w    (CLI only)    Tell ParM to open its own window rather than 
  84.                                 taking CLI one's.
  85.     -x    LEFTEDGE    left edge of ParM Window (default 0)
  86.     -y    TOPEDGE        top edge of ParM Window (default 0)
  87.     -d    DETAILPEN    detail pen of ParM Window (default 3)
  88.     -b    BLOCKPEN    block pen of ParM Window (default 2)
  89.     -c    MENUCOLOR    color for ParM's main menu (default Window 
  90.                 detail pen)
  91.     -f    CONFIGFILE    Configuration file.
  92.  
  93.     -h or anything wrong to get help when run from CLI.
  94.  
  95.     To use workbench tool types, just use the keyword followed by an "="
  96.     and the value needed. For example
  97.  
  98.         DETAILPEN=1
  99.  
  100.     this is equivalent to
  101.  
  102.         RunBack >NIL: ParM -d1        when run from CLI.
  103.  
  104.     if you specify any of the -x,-y,-d,-b options when run from cli, a
  105.     window will be open and -w option is useless.
  106.  
  107.  
  108. Configuration file:
  109.  
  110.     Configuration file looks like a structured program. You should indent
  111.     your lines to make the file as readable as possible.
  112.  
  113.     The default configuration file should be in the S: directory and be
  114.     named ParM.cfg.
  115.  
  116.     The configuration file defines the menus you want, and what commands
  117.     they will run.
  118.     Comments begin with a #, and continue until the end of the line.
  119.     Upper and lowercase does not make a difference.
  120.     You can also define the command console window.
  121.  
  122.     CMDWIN    console_name
  123.  
  124.         This will override the default console used for Command output
  125.         which is "CON:0/11/640/100 Command Window" This should be 
  126.         placed anywhere in the file but better be at top of it.
  127.  
  128.     COLOR n
  129.  
  130.         This will set the foreground pen color for new items.  You can
  131.         change this as often as you want.  The arguments is the pen 
  132.         number to use. The default is window detail pen. If the color 
  133.         was window block pen, the item would be invisible, in this 
  134.         case, ParM replaces the color with window detail pen.
  135.  
  136.     MENU menu_name
  137.  
  138.         Creates a new menu. Each menu must have at least one item or
  139.         submenu.
  140.  
  141.     SUBMENU submenu_name
  142.  
  143.         Creates a new submenu. Each submenu must have at least one 
  144.         item and can't have submenus.  Each SUBMENU must end with 
  145.         an ENDSUBMENU
  146.  
  147.     ENDSUBMENU
  148.  
  149.         See SUBMENU.
  150.  
  151.     ITEM [{command-char}] item_name command_def
  152.  
  153.         Defines a new menu item. Each item definition must have an
  154.         item_name and an associated command. Each item is linked to 
  155.         the current menu or submenu. An ENDSUBMENU statement tells 
  156.         ParM to attach next items to the current menu rather than to 
  157.         the current submenu.  If any of the menu, submenu and item 
  158.         names may contain whitespaces. In this case, enclose the name
  159.         in double quotes.  A command character may be defined for the 
  160.         menu item by putting the character after the ITEM keyword and 
  161.         surround it with {}'s.    Command syntax is decribed below.
  162.  
  163.         command_def
  164.  
  165.             Programs can be run in three ways: CLI, RB, and WB.
  166.  
  167.             1) CLI syntax
  168.  
  169.             CLI console command [STACK n] [PRI n] [args]
  170.  
  171.         This mode should be used if you want your command to have a
  172.         console window for its output. Otherwise, you should use
  173.         the RB mode. You must specify a valid console window. For
  174.         example, NIL: doesn't work. In such a case, ParM will pop
  175.         up a requester telling you it can't open the window.  STACK
  176.         and PRI are optionnal. If STACK is less than the default
  177.         stack specified in ParM.h, STACK will be set to this
  178.         default stack. It is currently 4096 bytes.  Actually, the
  179.         console is immediately closed after the program ends. We
  180.         hope to fix this in future release.  For example, I use
  181.         this mode to Format my floppies, and I see in a little
  182.         window the format process.
  183.  
  184.             2) RB syntax
  185.  
  186.             RB command [args]
  187.  
  188.         Execute command in CLI mode with any input/output.  You
  189.         MUST have the Run command in your C: directory.  You can't
  190.         use redirection since it is already redirected and
  191.         indirected to and from NIL:.
  192.  
  193.             3) WB syntax
  194.  
  195.             WB command
  196.  
  197.         Execute command in WorkBench mode. You must have a .info
  198.         file associated with the executable one. You can't leave
  199.         ParM until all WB processes aren't finished. No arguments
  200.         are allowed in this mode.
  201.  
  202.  
  203.     For both CLI and RB modes, your command is searched first in arp
  204.     resident list and then in CLI Path at time ParM was run. To know the
  205.     path in which ParM search its commands, just issue the Path command 
  206.     in the requester of ParM Command command, or open a newcli or shell
  207.     from ParM and issue the Path command.
  208.  
  209.     A config file is given with ParM as an example.
  210.  
  211.  
  212. ParM commands:
  213.  
  214.     Open:        Pops up a requester asking to select the new 
  215.             config file. 
  216.     UpDate:      UpDate the menu reloading the config file. 
  217.             Usefull if you modify the config file while ParM 
  218.             is running.  
  219.     Command:     Allows you to execute a single CLI command.  
  220.     Change Dir:     Changes ParM current directory. All CLI and RB 
  221.             commands will inherit ParM current directory.  
  222.     Quit:         Why? You don't like it!
  223.  
  224.  
  225. Limitations:
  226.  
  227.     Redirection can not be done for RB programs, since the code already
  228.     does redirection to and from NIL:.
  229.  
  230.     Scripts cannot be executed with the CLI option. This problem come from
  231.     the arp function ASyncRun(), and not from ParM. Script file stays
  232.     locked and nothing happen.
  233.  
  234.     Don't use characters of ascii value over 127 such as characters with
  235.     accents, strange things happen.
  236.  
  237.     Syntax of the script file is not completely checked to preserve code
  238.     size small. So error analysis shouldn't easy in certain cases. For the
  239.     same reason, the position of the error is mentioned as a char number in
  240.     the script file. For CygnusEd users, it is easy to jump to it, but for
  241.     other text editors, I don't know. Sorry but I don't want to lose my
  242.     time counting the line number of the error.
  243.  
  244.  
  245. Bugs:
  246.  
  247.     This is not really a ParM bug, but if you start a compressed program in
  248.     WorkBench mode and there is not enough memory for decompression, you
  249.     will never can quit ParM because WorkBench startup message is never
  250.     replied.
  251.  
  252.  
  253. Future plans:
  254.  
  255. -Join the CLI and RB options in only one, making STACK and PRI available
  256.  for both, and console window optionnal. The solution may be in
  257.  ASyncRun().  The problem is that the documentation for this function is
  258.  far from perfect and we couldn't have better results than ParM actually
  259.  does. If someone knows or find a solution, please contact us. See
  260.  bottom of file.
  261. -Having an option to let user close the console in CLI mode.
  262. -Making Command function asyncronous and having better input handle.
  263.  
  264.  
  265. Release notes:
  266.  
  267.     1.0:    Internal. Major MyMenu rework.
  268.  
  269.     1.1:    First official release.
  270.             Old CLI option changed to RB (stands for RunBack).
  271.             New CLI option added.
  272.             Config file syntax changed. (Old was MyMenu's one).
  273.  
  274.  
  275. Acknowledgements:
  276.  
  277.     The first release (internal) of ParM was a major rework of MyMenu by
  278.     Darin Johnson. The problem was that it wasn't possible to have MyMenu
  279.     without workbench, and program started from MyMenu didn't have a Path.
  280.  
  281.     So, lots of thanks to Darin Johnson for menu allocations and workbench
  282.     run. The idea of attaching menus to the CLI and some other ideas came
  283.     from a friend who also made a menu but wasn't easy to configure.
  284.  
  285.  
  286. Signature:
  287.  
  288.     S.R. & P.C.  This is not Status Register and Program Counter but
  289.     Sylvain Rougier & Pierre Carrette.  We are Frenchies so we hope the
  290.     documentation is readable. We put our work in making english language
  291.     comments, but it isn't allways easy, so be fair with us.
  292.  
  293.  
  294. Donnations:
  295.  
  296.     If you enjoy this program, send donnations and/or bugs report to:
  297.  
  298.         Sylvain Rougier
  299.         Coiffure W
  300.         39 rue Carnot
  301.         86000 Poitiers
  302.         France.
  303.  
  304.